<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>ex::debugging - Simple debugging in your code with compile-time constants</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:Gentoo@undef.domain" />
</head>

<body style="background-color: white">

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<ul>

		<li><a href="#functional_style">Functional style</a></li>
		<li><a href="#oo_style">OO style</a></li>
		<li><a href="#old_style">Old style</a></li>
	</ul>

	<li><a href="#perfomance">PERFOMANCE</a></li>
	<li><a href="#exports">EXPORTS</a></li>
	<li><a href="#caveats">CAVEATS</a></li>
	<ul>

		<li><a href="#not_scoped">NOT SCOPED</a></li>
		<li><a href="#requirements_of_sign">REQUIREMENTS OF SIGN</a></li>
		<li><a href="#collisions">COLLISIONS</a></li>
	</ul>

	<li><a href="#author">AUTHOR</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>ex::debugging - Simple debugging in your code with compile-time constants</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
        use ex::debugging +DEBUGLEVEL;
        use ex::debugging -DEBUGLEVEL;
        use ex::debugging; # defaults to DEBUGLEVEL +1;
        no ex::debugging;
        
Please, note, this will not work (because of explicit empty list doesn't call C&lt;import&gt;):</pre>
<pre>
        use ex::debugging ();
        no ex::debugging ();</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p><code>ex::debugging</code> was designed to replace commonly used <code>warn sprintf ... if $DEBUG</code>
There are two interfaces the same time: functional and OO;</p>
<p>
</p>
<h2><a name="functional_style">Functional style</a></h2>
<p>Have some unclear restriction: There MUST be a <code>+</code> or <code>-</code> sign after the debug function.
Otherwise, you'll get syntax error, when debugging will be disabled.</p>
<dl>
<dt><strong><a name="item_debug__2b_level_2c_expr_2c_list_3b">debug + LEVEL, EXPR, LIST;</a></strong>

</dl>
<p>Writes message to debug log (default - STDERR).
Message will be created using <code>sprintf EXPR,LIST</code>.
LIST will be remapped, so you'll see the undef as ``&lt;undef&gt;'' and empty string as ``''''
Examples:</p>
<pre>
        debug+0 =&gt; 'my test: %s',$var;
        # Produces to STDERR something like:
        # [main:10:] my test: &lt;undef&gt;</pre>
<p>Current default output format is:</p>
<pre>
        [ PACKAGE, LINE, SUB ] MESSAGE</pre>
<p>The sub will be get from stack, untill it differs from __ANON__.
So you'll se (if not called from main::) the first named sub.</p>
<p>
</p>
<h2><a name="oo_style">OO style</a></h2>
<p>Uses autocreated function <code>d</code> to access the debugging object.
It defines 5 methods: <code>debug</code>, <code>info</code>, <code>log</code>, <code>warn</code>, <code>error</code> with the levels 2..-2 respective.
Also there are a definition of <code>assert</code></p>
<pre>
        d-&gt;debug('my test: %s',$var); # equivalent to debug+2 =&gt; 'my test: %s', $var;
        d-&gt;warn('something wrong with me'); # equivalent to debug-1 =&gt; '...';</pre>
<p>Also, methods <code>warn</code> and <code>error</code> will work, even if <code>no ex::debugging</code> in effect.</p>
<p>
</p>
<h2><a name="old_style">Old style</a></h2>
<p>Also this module provides well known constant DEBUG, which will work even at compile time</p>
<pre>
        warn &quot;Something&quot; if DEBUG;
        # will be threated as C&lt;warn &quot;Something&quot;&gt; when DEBUG in effect
        # and as nothing when DEBUG is not in effect</pre>
<p>
</p>
<hr />
<h1><a name="perfomance">PERFOMANCE</a></h1>
<p>Default routines give very small overhead, much smaller than call to empty subroutine, but the fastest
way with no overhead at all is the old well known if DEBUG. Sad but true</p>
<pre>
        debug+0 =&gt; 'fastest debug' if DEBUG;
        assert+0 =&gt; 1==2, 'fastest assert' if DEBUG;
        d-&gt;assert(1==2,'fastest assert') if DEBUG;</pre>
<p>
</p>
<hr />
<h1><a name="exports">EXPORTS</a></h1>
<p>This package implicitly exports to the caller's namespace next subroutines: <code>DEBUG</code>, <code>debug</code>, <code>d</code></p>
<p>
</p>
<hr />
<h1><a name="caveats">CAVEATS</a></h1>
<p>
</p>
<h2><a name="not_scoped">NOT SCOPED</a></h2>
<p>The pragma is a per script, not a per block lexical.  Only the last
<code>use ex::debugging</code> or <code>no ex::debugging</code> matters, and it affects 
<strong>the whole script</strong>.
The multiple use of this pragma is discouraged.</p>
<p>
</p>
<h2><a name="requirements_of_sign">REQUIREMENTS OF SIGN</a></h2>
<p>Functional style uses compile-time hack, and when <code>no debugging</code> in effect, function <code>debug</code> replaced with 0;</p>
<p>So the statement <code>debug+0 =</code> ...&gt; converts to <code>0+0, ...</code> (May be checked using <code>B::Deparse</code>)</p>
<p>When <code>use debugging</code> is in effect <code>debug+0 =</code> ...&gt; converts to <code>debug( +0, ... )</code></p>
<p>Without a sign <strong>the syntax is erroneous</strong> when no debugging: <code>0 0, ...</code></p>
<p>If somebody knows, how to hack this (without source filters ;), let me know.</p>
<p>
</p>
<h2><a name="collisions">COLLISIONS</a></h2>
<p>This package can't be used together with Carp::Assert.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Mons Anderson &lt;<a href="mailto:inthrax@gmail.com">inthrax@gmail.com</a>&gt;

</p>

</body>

</html>
